/*
 Copyright (C) 2008 Richard Gomes

 This source code is release under the BSD License.

 This file is part of option, a free-software/open-source library
 for financial quantitative analysts and developers - http://option.org/

 option is free software: you can redistribute it and/or modify it
 under the terms of the option license.  You should have received a
 copy of the license along with this program; if not, please email
 <jquant-devel@lists.sourceforge.net>. The license is also available online at
 <http://www.option.org/index.php/LICENSE.TXT>.

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.

 option is based on QuantLib. http://quantlib.org/
 When applicable, the original copyright notice follows this notice.
 */

/*
 Copyright (C) 2004, 2005, 2006 StatPro Italia srl

 This file is part of QuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://quantlib.org/

 QuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 <quantlib-dev@lists.sf.net>. The license is also available online at
 <http://quantlib.org/license.shtml>.

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
 */

package org.option.termstructures;

import org.option.daycounters.DayCounter;
import org.option.time.Date;
import org.option.time.Frequency;
import org.option.time.Period;


/**
 * Interest rate term structure
 *利率期限结构基类
 * @author Richard Gomes
 */
public abstract interface YieldTermStructure extends TermStructure {

    /**
     * Return the implied zero-yield rate for a given date or time. In the former case, the time is calculated as a
     * fraction of year from the reference date.
     * 返回给定日期或时间的隐含零收益率。在前一种情况下，时间是从参考日期算起的年分数
     * <p>
     * The resulting interest rate has the required day-counting rule.
     *
     * @category zero yield rates
     */
    public abstract InterestRate zeroRate(
            final Date d,
            final DayCounter resultDayCounter,
            final Compounding comp);

    /**
     * Return the implied zero-yield rate for a given date or time. In the former case, the time is calculated as a
     * fraction of year from the reference date.
     * 返回给定日期或时间的隐含零收益率。在前一种情况下，时间是从参考日期算起的年分数
     * <p>
     * The resulting interest rate has the required day-counting rule.
     *
     * @category zero yield rates
     */
    public abstract InterestRate zeroRate(
            final Date d,
            final DayCounter resultDayCounter,
            final Compounding comp,
            final Frequency freq);

    /**
     * Return the implied zero-yield rate for a given date or time. In the former case, the time is calculated as a
     * fraction of year from the reference date.
     * <p>
     * The resulting interest rate has the required day-counting rule.
     *
     * @category zero yield rates
     */
    public abstract InterestRate zeroRate(
            final Date d,
            final DayCounter dayCounter,
            final Compounding comp,
            final Frequency freq,
            boolean extrapolate);

    /**
     * Return the implied zero-yield rate for a given date or time. In the former case, the time is calculated as a
     * fraction of year from the reference date.
     * <p>
     * The resulting interest rate has the same day-counting rule used by the
     * term structure. The same rule should be used for calculating the passed
     * double t.
     *
     * @category zero yield rates
     */
    public abstract InterestRate zeroRate(
            final/*@Time*/double time,
            final Compounding comp,
            final Frequency freq,
            boolean extrapolate);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     * 返回两个日期或时间之间的隐含远期利率。在前一种情况下，时间是从参考日期算起的年分数。由此产生的利率已达到规定的水平
     * <p>
     * Dates are not adjusted for holidays
     *
     * @category forward rates
     */
    public abstract InterestRate forwardRate(
            final Date d1,
            final Date d2,
            final DayCounter resultDayCounter,
            final Compounding comp);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     *
     * @category forward rates
     *
     * @see #forwardRate(Date, Date, DayCounter, Compounding)
     */
    public abstract InterestRate forwardRate(
            final Date d1,
            final Date d2,
            final DayCounter resultDayCounter,
            final Compounding comp,
            final Frequency freq);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     *
     * @category forward rates
     *
     * @see #forwardRate(Date, Date, DayCounter, Compounding)
     */
    public abstract InterestRate forwardRate(
            final Date d1,
            final Date d2,
            final DayCounter dayCounter,
            final Compounding comp,
            final Frequency freq,
            boolean extrapolate);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     *
     * @category forward rates
     *
     * @see YieldTermStructure#forwardRate(Date, Date, DayCounter,
     *      org.option.termstructures.InterestRate.Compounding, Frequency)
     */
    public abstract InterestRate forwardRate(
            final/*@Time*/double t1,
            final/*@Time*/double t2,
            final Compounding comp);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     *
     * @category forward rates
     *
     * @see YieldTermStructure#forwardRate(Date, Date, DayCounter,
     *      org.option.termstructures.InterestRate.Compounding, Frequency)
     */
    public abstract InterestRate forwardRate(
            final/* @Time */double t1,
            final/* @Time */double t2,
            final Compounding comp,
            final Frequency freq);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     * <p>
     * The resulting interest rate has the same day-counting rule used by the
     * term structure. The same rule should be used for the calculating the
     * passed times t1 and t2.
     *
     * @category forward rates
     */
    public abstract InterestRate forwardRate(
            final/* @Time */double time1,
            final/* @Time */double time2,
            final Compounding comp,
            final Frequency freq,
            boolean extrapolate);

    /**
     * Returns the implied forward interest rate between two dates
     * or times. In the former case, times are calculated as fractions of year
     * from the reference date. The resulting interest rate has the required
     * day-counting rule.
     *
     * @category forward rates
     *
     * @see #forwardRate(Date, Date, DayCounter, Compounding)
     */
    public abstract InterestRate forwardRate(
            final Date d,
            final Period p,
            final DayCounter resultDayCounter,
            Compounding comp,
            Frequency freq);

    /**
     * @category forward rates
     *
     * @see #forwardRate(Date, Date, DayCounter, Compounding)
     */
    public abstract InterestRate forwardRate(
            final Date d,
            final Period p,
            final DayCounter dayCounter,
            final Compounding comp,
            final Frequency freq,
            boolean extrapolate);

    /**
     * Returns the discount factor for a given date or time. In the
     * former case, the double is calculated as a fraction of year from the
     * reference date.
     *返回给定日期或时间的折扣系数。在前一种情况下，double计算为从基准日算起的一年的分数
     * @category discount factors
     */
    public abstract/* @DiscountFactor */double discount(final Date d);

    /**
     * Returns the discount factor for a given date or time. In the
     * former case, the double is calculated as a fraction of year from the
     * reference date.
     *
     * @category discount factors
     *
     * @see org.option.termstructures.YieldTermStructureImpl#discount(org.option.time.Date, boolean)
     */
    public abstract/* @DiscountFactor */double discount(final Date d, boolean extrapolate);

    /**
     * Returns the discount factor for a given date or time. In the
     * former case, the double is calculated as a fraction of year from the
     * reference date.
     * <p>
     * The same day-counting rule used by the term structure should be used for
     * calculating the passed double t.
     *
     * @category discount factors
     */
    public abstract/* @DiscountFactor */double discount(final/* @Time */double t);

    /**
     * Returns the discount factor for a given date or time. In the
     * former case, the double is calculated as a fraction of year from the
     * reference date.
     *
     * @category discount factors
     *
     * @see org.option.termstructures.YieldTermStructureImpl#discount(double, boolean)
     */
    public abstract/* @DiscountFactor */double discount(final/* @Time */double t, boolean extrapolate);

    /**
     *
     *
     * @category par rates
     *
     * @note though somewhat related to a swap rate, this method is not to be used for the fair rate of a real swap, since it does
     *       not take into account all the market conventions' details. The correct way to evaluate such rate is to instantiate a
     *       SimpleSwap with the correct conventions, pass it the term structure and call the swap's fairRate() method.
     *       虽然这种方法与掉期利率有一定的关联，但并不适用于实际掉期的公平利率，因为它没有考虑到所有市场惯例的细节。评估这种速率的正确方法是实例化
     *       使用正确约定的SimpleSwap，将术语结构传递给它并调用swap的fairRate（）方法。
     */
    public abstract/* @Rate */double parRate(int tenor, final Date startDate, final Frequency freq, boolean extrapolate);

    /**
     * Returns the implied par rate for a given sequence of payments at the given dates or times. In the former case, times are
     * calculated as fractions of year from the reference date.
     *返回给定日期或时间的给定付款序列的隐含票面利率。在前一种情况下，时间是从参考日期算起的年分数。
     * @category par rates
     *
     * @note though somewhat related to a swap rate, this method is not to be used for the fair rate of a real swap, since it does
     *       not take into account all the market conventions' details. The correct way to evaluate such rate is to instantiate a
     *       SimpleSwap with the correct conventions, pass it the term structure and call the swap's fairRate() method.
     *
     * @param dates
     * @param freq
     * @param extrapolate
     * @return the first date in the vector must equal the start date; the following dates must equal the payment dates.
     *          向量中的第一个日期必须等于开始日期；后面的日期必须等于付款日期
     * @see YieldTermStructure#parRate(int, Date, Frequency, boolean)
     */
    public abstract/* @Rate */double parRate(final Date[] dates, final Frequency freq, boolean extrapolate);

    /**
     * Returns the implied par rate for a given sequence of payments at the given dates or times. In the former case, times are
     * calculated as fractions of year from the reference date.
     *返回给定日期或时间的给定付款序列的隐含票面利率。在前一种情况下，时间是从参考日期算起的年分数
     * @category par rates
     *
     * @note though somewhat related to a swap rate, this method is not to be used for the fair rate of a real swap, since it does
     *       not take into account all the market conventions' details. The correct way to evaluate such rate is to instantiate a
     *       SimpleSwap with the correct conventions, pass it the term structure and call the swap's fairRate() method.
     *虽然这种方法与掉期利率有一定的关联，但并不适用于实际掉期的公平利率，因为它没有考虑到所有市场惯例的细节。
     * 评估这种速率的正确方法是用正确的约定实例化SimpleSwap，将术语结构传递给它并调用swap的fairRate（）方法
     * @return the first double in the vector must equal the start time; the
     *         following times must equal the payment times.
     *
     * @see YieldTermStructure#parRate(int, Date, Frequency, boolean)
     */
    public abstract/* @Rate */double parRate(final/* @Time */double[] times, final Frequency frequency, boolean extrapolate);

}